Developer CD Series 1996 July: Mac OS SDK/Dev.CD Jul 96 SDK/Dev.CD Jul 96 SDK1.toast/Development Kits (Disc 1)/OpenDoc Development Framework/ODFDev/ODF/Found/FWString/Include/FWPStr.h

Text File | 1996-04-25 | 26.7 KB | 781 lines | [TEXT/MPS ]

//========================================================================================
//
//    File:                FWPStr.h
//    Release Version:    $ ODF 1 $
//
//    Copyright:    (c) 1993 - 1996 by Apple Computer, Inc., all rights reserved.
//
//========================================================================================

#ifndef FWPSTR_H
#define FWPSTR_H

#ifndef FWEXCLIB_H
#include "FWExcLib.h"
#endif

#ifndef FWARDYNA_H
#include "FWArDyna.h"
#endif

#ifndef SLTXTPAR_H
#include "SLTxtPar.h"
#endif

#ifndef SLSTRREP_H
#include "SLStrRep.h"
#endif

//========================================================================================
//    Forward declarations
//========================================================================================

struct ODIText;
class FW_CReadableStream;
class FW_CWritableStream;
class FW_CString;

//========================================================================================
//    CLASS FW_CString
//
//    Characters in strings may occupy one, two, and possibly more bytes.
//  The number of characters in the string is therefore not necessarily equal
//    to the number of bytes in the string.
//
//    The "length" of the string is measured in characters.
//  The "byteLength" of the string is measured in bytes.
//  The "capacity" of the string is measure in bytes.
//
//========================================================================================

class FW_CString
{
public:
    FW_DECLARE_CLASS
    FW_DECLARE_AUTO(FW_CString)

//----------------------------------------------------------------------------------------
//    Initialization/Destruction
//
public:
    virtual ~FW_CString();
    FW_CString();
    FW_CString(const FW_CString& other);
    FW_CString(FW_HString rep);

    FW_CString(ODIText *text);
    FW_CString(const char* text);
    FW_CString(const char* text, FW_ByteCount byteLength);

    FW_CString(const char* text, const FW_Locale& locale);
    FW_CString(const char* text, FW_ByteCount byteLength, const FW_Locale& locale);

    operator FW_HString() const { return fRep; }
    operator FW_HString*();

//----------------------------------------------------------------------------------------
//    Character access
//
public:
    FW_LChar operator[](FW_CharacterPosition position) const;
        // This function may be expensive for some character sets!
        // Note that it returns a "long character", which may be 1, 2, or possibly more bytes

//----------------------------------------------------------------------------------------
//    Assignment
//
public:
    void  operator=(const FW_CString& other);
    void  operator=(ODIText *text);
    void  operator=(const char* text);

//----------------------------------------------------------------------------------------
//    Storage Manipulation
//
public:
    FW_ByteCount GrowCapacity(FW_ByteCount count);
        // If possible, grow the capacity to count bytes.
        // Return the actual capacity, which may be less or more than count.

//----------------------------------------------------------------------------------------
//    Basic accessors
//
public:
    FW_ByteCount GetByteLength() const;
        // Return the number of bytes actually in use for the string

    FW_CharacterCount GetCharacterLength() const;
        // Return the number of characters actually in use for the string.
        // Note that with some character sets this may be significantly more expensive
        // to call than GetByteLength!

    FW_ByteCount GetCapacity() const;
        // Return the number of bytes that may currently be used without growing capacity.
        // Note that GrowCapacity can be used to extend the capacity beyond the current limit.

    void GetLocale(FW_Locale& locale) const;

    FW_Boolean IsEmpty() const;
        // Returns true if the string is the empty string, i.e. it's bytelength is 0.

//----------------------------------------------------------------------------------------
//    Access to internals, use with caution!
//
public:
    const char* RevealBuffer() const;
        // This function is provided for convenience but is potentially dangerous!!
        // Do not cast away const and then modify the string!
        // Do not save the return value and expect it to be valid after calling
        // any string manipulation method that modifies the string!
        // NOTE: This is not a NUL-terminated string! Use GetByteLength to determine
        // how many bytes may be accessed.

    ODIText* RevealODIText() const;
        // This function is provided for convenience but is potentially dangerous!!
        // RevealODIText may be used when passing a String to an OpenDoc interface
        // that takes an ODIText* as an "in" parameter.  Do not use this function to
        // receive a string from OpenDoc!  Also, do not save the return value!
        // Any string manipulation method that modifies the string may invalidate
        // ODIText.

//----------------------------------------------------------------------------------------
// Streaming
public:

    static void* Read(FW_CReadableStream& stream, FW_ClassTypeConstant type);

    static void Write(FW_CWritableStream& stream, FW_ClassTypeConstant type, const void *object);

    FW_CReadableStream& PrivRead(FW_CReadableStream& stream);

    FW_CWritableStream& PrivWrite(FW_CWritableStream& stream) const;

    friend inline FW_CReadableStream& operator>>(FW_CReadableStream& stream, FW_CString& string);
    friend inline FW_CWritableStream& operator<<(FW_CWritableStream& stream, const FW_CString& string);

//----------------------------------------------------------------------------------------
//    String Manipulation
//
public:
    void Retrieve(char* destination,
                  FW_ByteCount numberBytes,
                  FW_BytePosition position) const;
        // Retrieve numberBytes of bytes starting at position.
        // Copy bytes into the destination.

    void Delete(FW_ByteCount numberBytes,
                FW_BytePosition position);
        // Delete numberBytes bytes, starting at position.

    void Insert(const char* bytes,
                FW_ByteCount numberBytes,
                FW_BytePosition position);
        // Insert bytes into string just before the character at positition.
        // Insert at position GetByteLength() appends the bytes.
        // Insert at position 0 prepends the bytes.

    void Insert(ODIText* text, FW_BytePosition position);
        // Insert text at position.

    void Insert(const FW_CString &string, FW_BytePosition position);
        // Insert string at position.

    void ReplaceAll(ODIText* text);
        // Replace entire contents of this string with text.

    void ReplaceAll(const FW_CString &string);
        // Replace entire contents of this string with string.

    void ReplaceAll(const char* bytes, FW_ByteCount numberBytes);
        // Replace entire contents of this string with bytes.

    void ReplaceAll(const char* string);
        // Replace entire contents of this string with (nul-terminated) string.

    void ReplaceAll(const FW_PascalChar* string);
        // Replace entire contents of this string with pascal string.

    void Append(const FW_CString &string);
        // Append string onto end of this string.

    void Append(ODIText* text);
        // Append text onto end of this string.

    void Append(const char* bytes, FW_ByteCount numberBytes);
        // Append bytes onto end of this string.

    void Append(const char* string);
        // Append (nul-terminated) string onto end of this string.

    void Append(char character);
        // Append a single character onto the end of this string.

    void Prepend(const FW_CString &string);
        // Prepend string onto beginning of this string.

    void Prepend(ODIText* text);
        // Prepend text onto beginning of this string.

    void Prepend(const char* bytes, FW_ByteCount numberBytes);
        // Prepend bytes onto beginning of this string.

    void Prepend(const char* string);
        // Prepend (nul-terminated) string onto beginning of this string.

    void Truncate(FW_BytePosition position);
        // Truncate string at position.  Truncate(0) clears string.

    void operator+=(const FW_CString &string);
        // Append string onto the end of this string.

    void operator+=(ODIText* text);
        // Append string onto the end of this string.

    void operator+=(const char* string);
        // Append (nul-terminated) string onto the end of this string.

    void operator+=(char character);
        // Append a single character onto the end of this string.

//----------------------------------------------------------------------------------------
//    Exporting Functions
//
public:
    void ExportCString(char* buffer) const;
        // Copy contents of this string to external C string buffer.
        // buffer will contain NUL-terminated C string.
        // It is client's responsibility to ensure buffer is large enough.

    void ExportPascal(FW_PascalChar* buffer) const;
        // Copy contents of this string to external 'Pascal' buffer.
        // buffer will contain Pascal string with length byte at buffer[0].
        // It is client's responsibility to ensure buffer is large enough.

//----------------------------------------------------------------------------------------
//    Numeric Conversion Functions
//
public:
    long            ParseAsSignedInteger() const;
    unsigned long    ParseAsUnsignedInteger() const;
    unsigned long    ParseAsHexadecimalInteger() const;
    double            ParseAsRealNumber() const;

    void            ReplaceAllAsSignedDecimalInteger(long integer);
    void            ReplaceAllAsUnsignedDecimalInteger(unsigned long integer);
    void            ReplaceAllAsHexadecimalInteger(unsigned long integer);
    void            ReplaceAllAsRealNumber(double real, short fracDigits = 2);

//----------------------------------------------------------------------------------------
//    Comparison Functions
//
public:
    friend FW_Boolean operator==(const FW_CString &string1, const FW_CString &string2);
    friend FW_Boolean operator!=(const FW_CString &string1, const FW_CString &string2);
    friend FW_Boolean operator<(const FW_CString &string1, const FW_CString &string2);
    friend FW_Boolean operator>(const FW_CString &string1, const FW_CString &string2);
    friend FW_Boolean operator<=(const FW_CString &string1, const FW_CString &string2);
    friend FW_Boolean operator>=(const FW_CString &string1, const FW_CString &string2);

//----------------------------------------------------------------------------------------
//    Searching & Substitution Functions
//
public:

    void ToUpper();
    void ToLower();

    FW_Boolean Substitute(const FW_CString &searchString,
                          const FW_CString &substitutionString);

    FW_Boolean FindSubString(const FW_CString &subString,
                             FW_BytePosition &foundPosition,
                             FW_BytePosition startPosition=0) const;

    FW_Boolean FindCharacter(FW_LChar character,
                             FW_BytePosition &foundPosition,
                             FW_BytePosition startPosition=0,
                             FW_FindDirection direction=FW_kForwards) const;

protected:
    FW_HString    fRep;
};

//----------------------------------------------------------------------------------------
// Inline functions
//----------------------------------------------------------------------------------------

inline FW_CReadableStream& operator>>(FW_CReadableStream& stream, FW_CString& string)
{
    return string.PrivRead(stream);
}

inline FW_CWritableStream& operator<<(FW_CWritableStream& stream, const FW_CString& string)
{
    return string.PrivWrite(stream);
}

//========================================================================================
//    CLASS FW_CAcquireNulTerminatedString
//========================================================================================

class FW_CAcquireNulTerminatedString
{
public:
    FW_DECLARE_AUTO(FW_CAcquireNulTerminatedString)

    FW_CAcquireNulTerminatedString(const FW_CString& string);
    ~FW_CAcquireNulTerminatedString();
    operator const char*() const
        { return fExportedString; }

private:
    char* fExportedString;
};

//========================================================================================
//    CLASS FW_CAcquireNulTerminatedString255
//========================================================================================

class FW_CAcquireNulTerminatedString255
{
public:
    FW_CAcquireNulTerminatedString255(const FW_CString& string);
    // no destructor necessary
    operator const char*() const
        { return fExportedString; }

private:
    char fExportedString[255];
};

//========================================================================================
//    FW_CString inline functions
//========================================================================================

//----------------------------------------------------------------------------------------
//    FW_CString::GetByteLength
//----------------------------------------------------------------------------------------

inline FW_ByteCount FW_CString::GetByteLength() const
{
    return FW_PrivString_GetByteLength(fRep);
}

//----------------------------------------------------------------------------------------
//    FW_CString::GetCapacity
//----------------------------------------------------------------------------------------

inline FW_ByteCount FW_CString::GetCapacity() const
{
    return FW_PrivString_GetCapacity(fRep);
}

//----------------------------------------------------------------------------------------
//    FW_CString::IsEmpty
//----------------------------------------------------------------------------------------

inline FW_Boolean FW_CString::IsEmpty() const
{
    return GetByteLength() == 0;
}

//----------------------------------------------------------------------------------------
//    FW_CString::GetLocale
//----------------------------------------------------------------------------------------

inline void FW_CString::GetLocale(FW_Locale& locale) const
{
    FW_PrivString_GetLocale(fRep, &locale);
}

//----------------------------------------------------------------------------------------
//    FW_CString::RevealBuffer
//----------------------------------------------------------------------------------------

inline const char* FW_CString::RevealBuffer() const
{
    return FW_PrivString_RevealBuffer(fRep);
}

//----------------------------------------------------------------------------------------
//    FW_CString::RevealODIText
//----------------------------------------------------------------------------------------

inline ODIText* FW_CString::RevealODIText() const
{
    return FW_PrivString_RevealODIText(fRep);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Retrieve
//----------------------------------------------------------------------------------------

inline void FW_CString::Retrieve(char* destination,
              FW_ByteCount numberBytes,
              FW_BytePosition position) const
{
    FW_PrivString_Retrieve(fRep, destination, numberBytes, position);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Delete
//----------------------------------------------------------------------------------------

inline void FW_CString::Delete(FW_ByteCount numberBytes,
            FW_BytePosition position)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_Delete(fRep, numberBytes, position, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Truncate
//----------------------------------------------------------------------------------------

inline void FW_CString::Truncate(FW_BytePosition position)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_Truncate(fRep, position, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Insert
//----------------------------------------------------------------------------------------

inline void FW_CString::Insert(const char* bytes,
            FW_ByteCount numberBytes,
            FW_BytePosition position)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_InsertBytes(fRep, bytes, numberBytes, position, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Insert
//----------------------------------------------------------------------------------------

inline void FW_CString::Insert(ODIText* text, FW_BytePosition position)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_InsertODIText(fRep, text, position, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Insert
//----------------------------------------------------------------------------------------

inline void FW_CString::Insert(const FW_CString &string, FW_BytePosition position)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_InsertStringRep(fRep, string.fRep, position, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ReplaceAll
//----------------------------------------------------------------------------------------

inline void FW_CString::ReplaceAll(ODIText* text)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_ReplaceAllODIText(fRep, text, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ReplaceAll
//----------------------------------------------------------------------------------------

inline void FW_CString::ReplaceAll(const FW_CString &string)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_ReplaceAllStringRep(fRep, string.fRep, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ReplaceAll
//----------------------------------------------------------------------------------------

inline void FW_CString::ReplaceAll(const char* bytes, FW_ByteCount numberBytes)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_ReplaceAllBytes(fRep, bytes, numberBytes, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ReplaceAll
//----------------------------------------------------------------------------------------

inline void FW_CString::ReplaceAll(const char* string)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_ReplaceAllBytes(fRep, string, FW_PrimitiveStringLength(string), &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ReplaceAll
//----------------------------------------------------------------------------------------

inline void FW_CString::ReplaceAll(const FW_PascalChar* string)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_ReplaceAllBytes(fRep, (const char*) (string+1), *string, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(ODIText* text)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_AppendODIText(fRep, text, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(const FW_CString &string)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_AppendStringRep(fRep, string.fRep, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(const char* bytes, FW_ByteCount numberBytes)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_AppendBytes(fRep, bytes, numberBytes, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(const char* string)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_AppendBytes(fRep, string, FW_PrimitiveStringLength(string), &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Append
//----------------------------------------------------------------------------------------

inline void FW_CString::Append(char character)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_AppendBytes(fRep, &character, 1, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Prepend
//----------------------------------------------------------------------------------------

inline void FW_CString::Prepend(const FW_CString &string)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_PrependStringRep(fRep, string.fRep, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Prepend
//----------------------------------------------------------------------------------------

inline void FW_CString::Prepend(ODIText* text)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_PrependODIText(fRep, text, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Prepend
//----------------------------------------------------------------------------------------

inline void FW_CString::Prepend(const char* bytes, FW_ByteCount numberBytes)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_PrependBytes(fRep, bytes, numberBytes, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Prepend
//----------------------------------------------------------------------------------------

inline void FW_CString::Prepend(const char* string)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_PrependBytes(fRep, string, FW_PrimitiveStringLength(string), &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator+=
//----------------------------------------------------------------------------------------

inline void  FW_CString::operator+=(const FW_CString &string)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_AppendStringRep(fRep, string.fRep, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator+=
//----------------------------------------------------------------------------------------

inline void  FW_CString::operator+=(ODIText* text)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_AppendODIText(fRep, text, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator+=
//----------------------------------------------------------------------------------------

inline void  FW_CString::operator+=(const char* string)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_AppendBytes(fRep, string, FW_PrimitiveStringLength(string), &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator+=
//----------------------------------------------------------------------------------------

inline void  FW_CString::operator+=(char character)
{
    FW_PlatformError error = 0;
    fRep = FW_PrivString_AppendBytes(fRep, &character, 1, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ExportCString
//----------------------------------------------------------------------------------------

inline void FW_CString::ExportCString(char* buffer) const
{
    FW_PrivString_ExportCString(fRep, buffer);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ExportPascal
//----------------------------------------------------------------------------------------

inline void FW_CString::ExportPascal(FW_PascalChar* buffer) const
{
    FW_PrivString_ExportPascalString(fRep, buffer);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ToUpper
//----------------------------------------------------------------------------------------

inline void FW_CString::ToUpper()
{
    FW_PlatformError error = 0;
    fRep =     FW_PrivString_ToUpper(fRep, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::ToLower
//----------------------------------------------------------------------------------------

inline void FW_CString::ToLower()
{
    FW_PlatformError error = 0;
    fRep =     FW_PrivString_ToLower(fRep, &error);
    FW_FailOnError(error);
}

//----------------------------------------------------------------------------------------
//    FW_CString::Substitute
//----------------------------------------------------------------------------------------

inline FW_Boolean FW_CString::Substitute(const FW_CString &searchString,
                                  const FW_CString &substitutionString)
{
    FW_PlatformError error = 0;
    FW_Boolean wasReplaced;
    fRep =     FW_PrivString_Substitute(fRep, searchString.fRep, substitutionString.fRep, &wasReplaced, &error);
    FW_FailOnError(error);
    return wasReplaced;
}

//----------------------------------------------------------------------------------------
//    FW_CString::FindSubString
//----------------------------------------------------------------------------------------

inline FW_Boolean FW_CString::FindSubString(const FW_CString &subString,
                                      FW_BytePosition &foundPosition,
                                     FW_BytePosition startPosition) const
{
    return FW_PrivString_FindSubString(fRep, subString.fRep, &foundPosition, startPosition);
}

//----------------------------------------------------------------------------------------
//    FW_CString::FindCharacter
//----------------------------------------------------------------------------------------

inline FW_Boolean FW_CString::FindCharacter(FW_LChar character,
                                     FW_BytePosition &foundPosition,
                                     FW_BytePosition startPosition,
                                     FW_FindDirection direction) const
{
    return FW_PrivString_FindCharacter(fRep, character, &foundPosition, startPosition, direction);
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator=
//----------------------------------------------------------------------------------------

inline void FW_CString::operator=(const FW_CString &other)
{
    ReplaceAll(other);
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator=
//----------------------------------------------------------------------------------------

inline void  FW_CString::operator=(ODIText *text)
{
    ReplaceAll(text);
}

//----------------------------------------------------------------------------------------
//    FW_CString::operator=
//----------------------------------------------------------------------------------------

inline void  FW_CString::operator=(const char* text)
{
    ReplaceAll(text);
}

#endif